 /*******************************************************************************
  * Copyright (c) 2003, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.navigator;

 import org.eclipse.ui.IActionBars;
 import org.eclipse.ui.IMemento;
 import org.eclipse.ui.actions.ActionGroup;

 /**
  * <p>
  * Provides actions from extensions for menu and
  * {@link org.eclipse.ui.IActionBars} contributions.
  * </p>
  * <p>
  * This abstract class should be extended by clients of the
  * <b>org.eclipse.ui.navigator.navigatorContent</b> extension point for
  * top-level and nested <b>actionProvider </b> elements.
  * </p>
  * <p>
  * {@link CommonActionProvider}s may be declared as top-level elements in the
  * extension point (e.g. an <b>actionProvider</b> element at the root of the
  * extension point). Alternatively, <b>actionProvider</b> elements may be
  * nested under a <b>navigatorContent</b> element, in which case they are
  * considered to be "associated" with that content extension. For more
  * information, see the <b>org.eclipse.ui.navigator.navigatorContent</b>
  * extension point.
  * </p>
  * <p>
  * Each action provider will have the opportunity to contribute to the context
  * menu when a user right clicks and also contribute to the {@link IActionBars}
  * each time the selection changes. Clients should re-configure the
  * {@link IActionBars} each time that {@link #fillActionBars(IActionBars)} is
  * called (which is once per selection changes). {@link #updateActionBars()}
  * will never be called from the {@link NavigatorActionService}. This behavior
  * is required since each selection could determine a different set of
  * retargetable actions. For instance, the "Delete" operation for a custom model
  * element is likely to be different than for a resource.
  * </p>
  * <p>
  * Therefore, each extension will have an opportunity to contribute to the
  * IActionBars based on the <b>possibleChildren</b> expression of the enclosing
  * <b>navigatorContent</b> extension or the <b>enablement</b> expression of
  * the <b>actionProvider</b> (for both top-level <b>actionProvider</b>s and
  * nested <b>actionProvider</b>s which only support a subset of the enclosing
  * content extensions <b>possibleChildren</b> expression).
  * <p>
  * Clients may extend this class.
  * </p>
  *
  * @since 3.2
  */
 public abstract class CommonActionProvider extends ActionGroup implements
         IMementoAware {

     private ICommonActionExtensionSite actionSite;

     /**
      * <p>
      * Initialize the current ICommonActionProvider with the supplied
      * information.
      * </p>
      * <p>
      * init() is guaranteed to be called before any other method of the
      * ActionGroup super class.
      *
      * @param aSite
      * The configuration information for the instantiated Common
      * Action Provider.
      */
     public void init(ICommonActionExtensionSite aSite) {
         actionSite = aSite;
     }

     /**
      * <p>
      * Restore the previous state of any actions using the flags in aMemento.
      * This method allows the state of any actions that persist from session to
      * session to be restored.
      * </p>
      *
      * <p>
      * The default behavior is to do nothing.
      * </p>
      *
      * @param aMemento
      * A memento that was given to the view part to restore its
      * state.
      */
     public void restoreState(IMemento aMemento) {
     }

     /**
      * <p>
      * Save flags in aMemento to remember the state of any actions that persist
      * from session to session.
      * </p>
      * <p>
      * Extensions should qualify any keys stored in the memento with their
      * plugin id
      * </p>
      *
      * <p>
      * The default behavior is to do nothing.
      * </p>
      *
      * @param aMemento
      * A memento that was given to the view part to save its state.
      */
     public void saveState(IMemento aMemento) {
     }

     /**
      *
      * @return The cached reference to the action site. Will only be non-null if
      * the subclass calls super.init() first.
      */
     protected final ICommonActionExtensionSite getActionSite() {
         return actionSite;
     }

 }

